Note: Most of the information in this blurb will be of use only to Macintosh programmers.
Blurbs are styled TextEdit panes which can be overlapped, dragged, closed, zoomed, grown, iconified, and scrolled.
Blurbs in a window that share a common graphics background, view region, and click interaction belong to the same blurb cluster. All blurb clusters in a window belong to the same blurb group. There are as many blurb groups in a program as there are windows with blurbs. One blurb manager record per program is the gateway to all blurbs in that program, and it is managed by the Blurb Manager.
• About The Blurb Manager
The Blurb Manager is 37 kilobytes of THINK Pascal object code that manages all blurbs in a program. Version 1.0 of the Blurb Manager can only be used in applications, since internally it makes use of globals referenced off of register A5 — you cannot use the Blurb Manager in stand alone code resources, desk accessories, drivers, etc.
The Blurb Manager was programmed using THINK Pascal 4.0.1. This version runs in THINK Pascal and THINK C environments. If the response warrants I will make it available to MPW users as well.
I wrote the Blurb Manager as a smaller counterpart to my 100 kB Windette Manager for fully editable TextEdit panes. (The Windette Manager supports standard Edit menu functionality in a popup menu accessible from every Windette marked as editable. You can set the text font, size, style, and color on a character by character basis.)
The Blurb Manager manages your specified hierarchy of blurbs in clusters and groups and automatically handles many blurb events itself, including:
1) fronting and activating a clicked blurb in a cluster;
2) dragging, growing, and zooming a blurb, and then efficiently re-drawing all overlapping blurbs in that cluster;
3) scrolling, auto-scrolling, and correctly hiliting text and pictures in blurbs;
4) notifying your program when
a) the cursor moves into a blurb;
b) the user clicks a close box;
c) the user clicks an iconify box;
The Blurb Manager maintains up-to-date visible regions for all blurbs in a program and does the right thing when drawing blurbs across multiple screens of different sizes, locations, and color properties, in much the same way as the Macintosh Window Manager draws windows across multiple screens.
The advantages to the Blurb Manager's use of TextEdit include smaller Blurb Manager code size (TextEdit's code is already part of the ToolBox), ease of implementation, familiarity to programmers, standardization, and generality (particularly when it comes to different script systems, such as right-to-left Hebrew script). The main disadvantage is TextEdit's 32 kB limit on the number of characters in a single record.
The Blurb Manager requires a Mac Plus or better, running System 6.0.5 or greater.
The code is 32-bit clean, and will run under virtual memory.
I have tested it on a Mac Plus, Mac Classic, Mac SE, Mac II, Mac II cx, Mac II si, Quadra 900 (with cache on), and PowerBook 140.
• Using Blurbs
Here are the steps needed to implement Blurbs in your program:
1) Use the Blurb Manager libraries and interface unit in any unit that makes Blurb Manager calls.
2) Call NewBlurbMgr before making any other Blurb Manager calls in your program. Store the returned handle for future use.
3) Call NewBlurbGroup for each window in which you want blurbs.
4) Call NewBlurbCluster for each new cluster you want in a window.
5) Call NewBlurb to create a new blurb.
6) Call IsBlurbEvent before processing the events of any window which has blurbs. IsBlurbEvent returns either kNotBlurbEvt or the type of blurb event that occurred. If it returns a blurb event the window need not process this Macintosh event any further. (IsBlurbEvent processes mouseDown events and cursor events in blurbs. Currently there are 15 different blurb events, including activate, drag, grow, default zoom, user zoom, close request, iconify request, set menu, menu result, text click and double-click, picture click and double-click, cursor into blurb, and scroll.)
7) Call IdleBlurb frequently in your event loop if you have any blurbs that have copiable text or pictures. This causes either the text caret or a selected picture to blink. (The picture blink interval is tied to the System-wide caret blink interval as selected by the user from the "General" control panel.)
8) Call DrawBlurbs when a window containing blurbs receives an update event.
9) Call SuspendBlurbs when a window containing blurbs is deactivated or your program is suspended under MultiFinder.
10) Call ResumeBlurbs when a window containing blurbs is activated or your program is resumed under MultiFinder.
11) Call DisposeBlurbGroup before closing a window having blurbs.
12) Call DisposeBlurbMgr before exiting your program.
Additional, optional Blurb Manager calls include:
DrawBlurbCluster
ShowBlurbCluster
HideBlurbCluster
OffsetBlurbCluster
SetBlurbClusterViewRgn
DisposeBlurbCluster
DrawBlurb — Normally you will just call DrawBlurbs when your window gets an update event.
ShowBlurb
HideBlurb
ActivateBlurb — Deactivates the previously active blurb and fronts the newly activated blurb — only needed if you explicitly, and programmatically, want to activate and front a blurb.
DeactivateBlurb — Does not change its layer.
OffsetBlurb
SizeBlurb — Resizes a blurb to the rectangle you specify.
FillBlurb — Puts a string, styled text, and/or pictures into a blurb.
EmptyBlurb — Disposes of all text and/or pictures in a blurb.
AddStringToBlurb — Appends a string with the specified style information to the end of a blurb's text.
SetBlurbTitle
CopyFromBlurb — Copies to the clipboard whatever is selected in a blurb — text or picture.
SetBlurbDefaultZoomRect
ScrollBlurbToChar — Programmatically scrolls the blurb to the specified occurrence of the specified character. (This is how the menu with this blurb works.)
SendBlurbToBack — Deactivates the specified blurb, if active, then puts it behind all other blurb's in its cluster. There is no need for a "BringBlurbToFrontCall" because that is exactly what ActivateBlurb does.
DisposeBlurb
There are no resources associated with the Blurb Manager.
• Data Types
Most Blurb Manager data types are documented in the Blurb Manager package available to licensees, and are made public to your program. We present only a sample here.
The NewBlurb call requires a blurb preferences handle with the following specification:
type
BlurbPrefsPtr = ^BlurbPrefs;
BlurbPrefsHnd = ^BlurbPrefsPtr;
BlurbPrefs = record
blurbRect: Rect;
blurbDragLimitRect: Rect;
blurbDefaultZoomRect: Rect;
minBlurbWidth: Integer;
minBlurbHeight: Integer;
startActive: Boolean;
startVisible: Boolean;
isDraggable: Boolean;
isCloseable: Boolean;
isIconifiable: Boolean;
isZoomable: Boolean;
isGrowable: Boolean;
isCopiable: Boolean;
isBorderless: Boolean;
hasVScroll: Boolean;
hasHScroll: Boolean;
doFastScroll: Boolean;
hasAdjustableText: Boolean;
blurbMenu: MenuHandle;
blurbSetMenuProc: ProcPtr;
blurbSetMenuData: Longint;
blurbCursorProc: ProcPtr;
blurbCursorData: Longint;
lineWidth: Integer;
blurbTitle: Str31;
startingFont: Str255;
startingFontSize: Integer;
blackAndWhiteBlurb: Boolean;
mainColor: Integer;
titleColor: Integer;
titleBarTopLeftColor: Integer;
titleBarBotRightColor: Integer;
titleBarStripesColor: Integer;
buttonColor: Integer;
buttonShadowColor: Integer;
blurbText: Handle;
blurbTextStyles: StScrpHandle;
blurbTextID: Integer;
blurbString: Str255;
blurbStringFont: Integer;
blurbStringFontSize: Integer;
blurbStringFontFace: Style;
blurbPictures: BlurbPicturesDataHnd;
blurbPicturesMarker: Char;
blurbRefCon: Longint;
end;
blurbRect: struct rect of new blurb - in the window's local coordinates.
blurbDragLimitRect: if the blurb is draggable no part of it will ever be dragged outside this rect.
blurbDefaultZoomRect: rect to which the blurb will zoom when not zooming to the user zoom rect.
minBlurbWidth: the Blurb Manager will never make the blurb wider than this.
minBlurbHeight: nor taller than this.
startActive: is the blurb initially active?
startVisible: draw the blurb immediately after creating it?
isDraggable: if true, the blurb will have a title bar.
isCloseable: if true, the blurb will have a close box - but only if the blurb is also draggable.
isIconifiable: if true, the blurb will have an iconify box - but only if the blurb is also draggable. When the user clicks this box your program will be notified of an iconify request. It's up to you what you do with this. Typically you would zoom to an icon then hide the blurb.
isZoomable: if true, the blurb will have a zoom box - but only if the blurb is also draggable.
isGrowable: if true, the blurb can be resized by dragging its grow icon.
isCopiable: must be true for text or pictures to be selectable and copiable to the ClipBoard.
isBorderless: can only be true if the blurb is not draggable, has no scrollbars, and is not growable. If true, the blurb will be drawn with a one-pixel wide white border around it.
doFastScroll: determines whether blurb gets custom fast scrolling.
hasAdjustableText: if true, the width of text lines in the blurb will always conform to the width of the blurb itself whenever it is resized; otherwise the line width is fixed at whatever width you specify in the lineWidth field below.
blurbMenu: if not nil, and the blurb is draggable, the Blurb Manager will draw the popup menu symbol in the blurb's titlebar. When the menu symbol is clicked, the Blurb Manager first calls your menuProc (see next entry), then pops up the menu, and finally reports back to your program (through the IsBlurbEvent mechanism) the menu result. It's up to you to do whatever you want to with this result — the Blurb Manager has no idea what your menu is about. You are completely responsible for allocating, inserting, maintaining and disposing this menu.
blurbSetMenuProc: if not nil, and the blurb has a menu, this procedure will be called before the Blurb Manager pops up the menu. This allows you to manipulate the menu however you may wish before it is displayed.
blurbSetMenuData: whatever you pass here will be returned as the single parameter to your blurbSetMenuProc.
blurbCursorProc: if not nil this procedure will be called whenever the cursor moves into a different blurb.
blurbCursorData: whatever you pass here will be returned as the single parameter to your blurbCursorProc.
lineWidth: see hasAdjustableText entry above.
blurbTitle: only displayed if blurb is draggable.
startingFont: determines initial font.
startingFontSize: determines initial font size.
blackAndWhiteBlurb: if true, the blurb will be drawn in standard Macintosh black and white style, ignoring all color specification fields below.
mainColor - buttonShadowColor: these are the various colors used to draw the blurb frame, titlebar, and grow icon if the blurb is not a blackAndWhiteBlurb. The colors are specified as color palette entries.
blurbText: if nil then blurbTextID is used unless it is less than 1, in which case blurbString is inserted (if not an empty string).
blurbTextStyles: style record to go with blurbText above.
blurbTextID: 'TEXT' resource ID used if greater than 0 and blurbText is nil.
blurbString: only inserted if blurbText is nil.
blurbStringFont, blurbStringFontSize, blurbStringFontFace: only used if blurbString is inserted.
blurbPictures: this is the information used by the Blurb Manager to display pictures in the blurb. You specify how many pictures there are, along with each picture's handle or resource ID, horizontal spacing, and copiablity.
blurbPicturesMarker: this character, interspersed throughout your text will be used by the Blurb Manager to maintain the vertical spacing of each picture in the blurb.
blurbRefCon: this is for your own private use.
The minimum space allocated for each blurb is 644 bytes.
• Routines
All Blurb Manager routines are described in detail in the Blurb Manager package using Inside Macintosh style.
• Summary of The Blurb Manager
Detailed information is provided in the Blurb Manager package.
